Pila 1.0 Beta 3 Fluff 7 ReadMe
By Darrin Massena (darrin@massena.com)
27 Oct 1996
Modifications by Mikael Klasson (fluff@geocities.com)
18 Mar 1998

Pila is a 68000 assembler that runs under Windows 95/NT and Linux and
produces Pilot executables. Documentation for Pila is in the HTML file
PilaUM.htm.

This version is of a BETA level of quality. That means it includes all
the documented features and has undergone a fair amount of public testing
to be sure they work. It also means that there are known bugs and anyone
using unstressed areas of the program may discover more bugs. If you
uncover any bugs or have suggestions on how to improve anything in the
Pila package (the program, documentation, this readme, etc) please send me
mail at darrin@massena.com. This is a part-time effort for me but I really
value your feedback and will respond as soon as I can.

Consult http://www.massena.com/darrin/pilot/pila.htm for an up-to-date
list of known bugs and other Pila status.

Consult http://fluff.home.ml.org if you're looking for info regarding the
"Fluff *" releases.

You will definitely want to get the entire ASDK package. You must for 
example have PilRC if you intend to assemble the sample files included.
Get it from http://www.massena.com/darrin/pilot/index.html

SPECIAL NOTES

- Certain invalid syntaxes used to cause the assembler to crash. I've 
  killed at least one responsible bug now. Tell me (fluff@geocities.com) 
  if you experience any more crashes!

- Pila sometimes reports the compressed size of an application's data 
  section as being larger than the uncompressed size! This is due to the
  overhead the PalmOS' compression format introduces. When the total size 
  of your data adds up to more than 50 bytes or so, the compressed size 
  should normally be smaller.

REVISION HISTORY

ALPHA 1 (7 Aug 1996)
- First release!

BETA 1 (10 Sep 1996)
- added Wes Cherry's PilRC (0.71), a tool for creating Pilot resources,
  to the Pila package
- added Bill Hunt's PilDis (Alpha 1), a tool for disassembling Pilot
  code resources
- added Sample.rcp file to demonstrate resource creation. Sample.rcp
  replaces mbar1.bin and tfrm1.bin which are removed
- added Sample.bat file to build Sample.prc
- added special equates to Pilot.inc for the serial library APIs
- implemented source file name printing in error messages
- implemented a statistics dump after successful assembly. Displays
  sizes for code, data, resource, and the entire PRC. Keep those PRCs
  small!
- implemented a very minor Startup.inc optimization
- fixed bug that was causing line numbers to be offset by one inside
  include files and off by another one in the 'including' file
- fixed a HUGE bug that caused the data section and A5 register to be
  improperly initialized
- updated Sample.asm to demonstrate data section access (amongst other
  things)
- updated PilaUM.htm to incorporate various suggestions I received
  from Alpha testers, including a new section on the PalmOS API
  calling convention and a pointer to an online version of the
  Motorola 680x0 Programmer's Reference Manual -- get it!

Beta 2 (2 Oct 1996)
- added 'align' directive for aligning code/data on user-defined boundaries
- added 'list' directive for enabling/disabling listing output
- added include path support via PILAINC environment variable
- added Copilot-compatible code symbol generation. Specify "-s" and your
  app's code symbols will be available while debugging under Copilot
- updated Startup.inc to use Wes' new directives (see below)
- updated documentation
- changed all errors to be output to stdout, rather than a mix of stdout/
  stderr
- added Wes Cherry's PilRCUI, a tool for previewing Pilot form resources,
  to the Pila package
- updated to Wes Cherry's PilRC version .8

Wes Cherry has been extending Pila and has added many new features to make
assembly language programming easier and less bug-prone. His new directives
and syntax support procedure parameter definition, procedure calling, trap
calling, local and global variable definition, and structure definition and
usage. Wow!

- the new directives are: call, systrap, syslibtrap, local, global, proc,
  beginproc, endproc, struct, endstruct, and sizeof
- added documentation for new directives to PilaUM.htm! Updated examples,
  etc to show new syntax
- Pila names (e.g., labels, equates) are now case sensitive. Instructions
  and directives remain case insensitive
- updated Pilot.inc to use the new structure syntax. Several incorrect
  structure member offsets were fixed in the process
- updated Sample.asm to use the new directives
- fixed the 'end' directive to work as it should and be optional

Beta 3 (2 Nov 1996)
- incorporated Pila into the ASDK package. No more separate Pila releases
- added '-t' command line switch to set PRC type
- fixed problems in Pilot.inc where fields containing small enumerations 
  were incorrectly sized as words instead of bytes
- added an 'align 2' directive to be emitted after each debug symbol
  ('-s' switch)
- fixed DATA 0 resource format to be compatible with future PalmOS upgrades
- fixed other small bugs

Beta 3 Fluff 4 (23 Jan 1998)
This is not an "official" release. I, Mikael Klasson (fluff@geocities.com),
have made the following extensions and so you should blame me for any bugs 
and stuff like that concerning them. They're not Darrin's fault ;)
- labels are local to the procedure if they start with a dot, e.g ".loop"
- a new directive, "incbin", allows you to include binary files straight 
  into your prc file
- implemented compression of the datasection
- fixed a bug with "ds.T X". Even if X was more than 1, only the first
  sizeof(T) bytes were initialized to zero

Beta 3 Fluff 5 (02 Feb 1998)
Linux fixes by Michael Dreher (michael@odo.boeblingen.netsurf.de)
- the PILAINC environment variable works under Linux as well
- pila compiles with fewer warnings under Linux

Beta 3 Fluff 6 (12 Feb 1998)
More Linux fixes by Michael Dreher (michael@odo.boeblingen.netsurf.de)
- gcc -Wall produces no warnings whatsoever now
- should, perhaps, with some luck, work well even under big-endian machines

Beta 3 Fluff 7 (18 Mar 1998)
Misc fixes by Mikael Klasson (fluff@geocities.com) and Michael Dreher
(michael@odo.boeblingen.netsurf.de)
- defining an address operand like (a6,6) instead of 6(a6) caused the 
  assembler to crash
- spaces in expressions didn't work very well
- compiles without warnings using glibc
- eliminated a few potential sources of bugs
